home *** CD-ROM | disk | FTP | other *** search
/ This Disc Bytes! / Power Computing - The Disc 2 - This Disc Bytes.ISO / mac / CodeWarrior 7 Lite for 68K / MacOS Support / Headers / Universal Headers / ErrMgr.h < prev    next >
Text File  |  1995-03-21  |  6KB  |  135 lines
  1. /*---------------------------------------------------------------------------*
  2.  |                                                                           |
  3.  |        <<< ErrMgr.h - Error File Manager Routines Header File >>>         |
  4.  |                                                                           |
  5.  |                               Ira L. Ruben                                |
  6.  |                                 07/23/87                                  |
  7.  |                                                                           |
  8.  |   Based on the Pascal version developed by Fred Forsman and Ira L. Ruben  |
  9.  |                                                                           |
  10.  |                  Copyright Apple Computer, Inc. 1987-1989                 |
  11.  |                           All rights reserved.                            |
  12.  |                                                                           |
  13.  *---------------------------------------------------------------------------*/
  14.  
  15. /* This file contains:
  16.  
  17. InitErrMgr(toolname, sysename, Nbrs)    -    ErrMgr initialization for C callers
  18. CloseErrMgr()                                                    - Close ErrMgr message files
  19. GetSysErrText(Nbr, Msg)                                - Get a system error message for a number
  20. GetToolErrText(Nbr, Insert, Msg)            -    Get a tool error message for a number
  21. AddErrInsert(insert, msgString)                -    Add an insert to a message
  22. addInserts(msgString, insert,...)            - Add a number of inserts to a message
  23.  
  24. */
  25.  
  26. #ifndef __ERRMGR__
  27. #define __ERRMGR__
  28.  
  29. #ifndef __TYPES__
  30. #include <Types.h>
  31. #endif
  32.  
  33. #ifdef __cplusplus
  34. extern "C" {
  35. #endif
  36.  
  37. extern void InitErrMgr(char *toolErrFilename, char *sysErrFilename,
  38.                                              Boolean showToolErrNbrs);
  39.     /*
  40.     ErrMgr initialization.    This must be done before using any other ErrMgr
  41.     routine.  Set showToolErrNbrs to true if you want all tool messages to contain
  42.     the error number following the message text enclosed in parentheses (e.g.,
  43.     "<msg txt> ([OS] Error <n>)"; system error messages always contain the error 
  44.     number).  The toolErrFileName parameter is used to specify the name of a 
  45.     tool-specific error file, and should be the NULL or a null string if not used
  46.     (or if the tool's data fork is to be used as the error file, see
  47.     GetToolErrText for futher details).     The sysErrFileName parameter is used to
  48.     specify the name of a system error file, and should normally be the NULL or a
  49.     null string, which causes the ErrMgr to look in the MPW Shell directory for
  50.     "SysErrs.Err" (see GetSysErrText).
  51.     
  52.     If InitErrMgr is NOT called prior to calling GetSysErrText or GetToolErrText,
  53.     then those routines, the first time they are called, will call InitErrMgr as
  54.     InitErrMgr(NULL, NULL, true).
  55.     
  56.     The following global may be set to true to allow a C caller to process all
  57.     strings as Pascal strings:
  58.     */
  59.  
  60. extern Boolean pascalStrings;      /* set to true for Pascal strings                    */
  61.     
  62.     /*    
  63.     This should be set PRIOR to calling InitErrMgr.  Once set, ALL strings, both
  64.     those passed to the ErrMgr as filenames and error message inserts, as well as
  65.     the messages returned by the ErrMgr will be Pascal strings.  There is NO
  66.     guarantee a '\0' byte is at the end of the string.  Results are unpredictable
  67.     if pascalStringsis set false after it has been set true!
  68.     */
  69.     
  70.  
  71. extern void CloseErrMgr(void);
  72.     /*
  73.     Ideally a CloseErrMgr should be done at the end of execution to make sure all
  74.     files opened by the ErrMgr are closed.  You can let normal program termination
  75.     do the closing.  But if you are a purist...
  76.     */
  77.  
  78.  
  79. extern char *GetSysErrText(short msgNbr, char *errMsg);
  80.     /*
  81.     Get the error message text corresponding to system error number errNbr from
  82.     the system error message file (whose name was specified in the InitErrMgr
  83.     call).  The text of the message is returned in errMsg and the function returns
  84.     a pointer to errMsg.  The maximum length of the message is limited to 254
  85.     characters.
  86.     
  87.     Note, if a system message filename was not specified to InitErrMgr, then the
  88.     ErrMgr assumes the message file contained in the file "SysErrs.Err".  This
  89.     file is first accessed as "{ShellDirectory}SysErrs.Err" on the assumption that
  90.     SysErrs.Err is kept in the same directory as the MPW Shell.  If the file
  91.     cannot be opened, then an open is attempted on "SysErrs.Err" in the System
  92.     Folder.
  93.     */
  94.  
  95.  
  96. extern char *GetToolErrText(short msgNbr, char *errInsert, char *errMsg);
  97.     /*
  98.     Get the error message text corresponding to tool error number errNbr from
  99.     the tool error message file (whose name was specified in the InitErrMgr
  100.     call).  The text of the message is returned in errMsg and the function returns
  101.     a pointer to errMsg.  The maximum length of the message is limited to 254
  102.     characters.  If the message is to have an insert, then ErrInsert should be a
  103.     pointer to it.  Otherwise it should be either be a null string or a NULL
  104.     pointer.
  105.     
  106.     Inserts are indicated in error messages by specifying a '^' to indicate where
  107.     the insert is to be placed.
  108.     
  109.     Note, if a tool message filename was not specified to InitErrMgr, then the
  110.     ErrMgr assumes the message file contained in the data fork of the tool calling
  111.     the ErrMgr.  This name is contained in the Shell variable {Command} and the
  112.     value of that variable is used to open the error message file.
  113.     */
  114.  
  115.  
  116. extern void AddErrInsert(unsigned char *insert, unsigned char *msgString);
  117.     /*
  118.     Add another insert to an error message string.    This call is used when more
  119.     than one insert is to be added to a message (because it contains more than
  120.     one '^' character).
  121.     */
  122.  
  123. extern unsigned char *addInserts(unsigned char *msgString, ...);
  124.     /*
  125.     Add a set of inserts to an error message string.  AddErrInsert is called for
  126.     each insert parameter specified.  Insertion strings are listed after the
  127.     msgString parameter.  Each insertion string should be of type unsigned char *.
  128.     The list of insertion strings must be terminated by a NULL pointer (e.g. 
  129.     (unsigned char *) NULL).
  130.     */
  131.     
  132. #ifdef __cplusplus
  133. }
  134. #endif
  135. #endif